Run Reference

Version latest

Run Reference for v0.1.0

$ docker run [docker-run-options] tomlau10/sandbox-run [options] <executable> [args]

• Related Docker Run Options
• Arguments
• General Options
• IO Setting Options
• Monitor Setting Options
• Result Json Format
• Parse Streams in Streaming Mode

Related Docker Run Options

Below is a list of docker run options which are useful when using Sandbox-Run.

--security-opts

• AppArmor on Ubuntu host blocked the use of ptrace in container
• Add --security-opts apparmor:unconfined to fix this issues
• NOT needed on Windows or Mac OS

--net

• Add --net none to disable network connection inside container

-w

• Set the working directory for sandbox-run, default is /vol

-v

• Mount a host directory to container
• Usually this is the working directory containing the code_file or executable, e.g.

  $ docker run -v $(pwd):/vol tomlau10/sandbox-run
  

-u

• The files created by the container is defaulted to be owned by root on Ubuntu host
• NO such issue on Windows or Mac OS
• Use following to fix any ownership or permission issues, i.e.

  $ docker run -u $(id -u):$(id -g) tomlau10/sandbox-run
  

-i

• Keep stdin open
• This switch is needed for -I in sandbox-run, see below

--entrypoint

• The default entrypoint is to run sandbox-run
• Use --entrypoint to change default program
• e.g. use make to compile using the Makefile of current directory

  $ docker run --rm --entrypoint sh -v $(pwd):/vol -u $(id -u):$(id -g) tomlau10/sandbox-run -c "make clean all"
  

Arguments

Arguments provided to Sandbox-Run.

<executable>

• The name of the executable
• Can be absolute path or relative path to current working directory
• The default working directory is /vol, use docker run -w <WORKDIR> ... to change
• If -c switch is on, this will be the output name of the executable

[args]

• Optional arguments provided to <executable>

General Options

General options for Sandbox-Run.

-h

• print help, then exit

-c <code_file>

• The code file for compilation
• Currently only support one of the following file extensions: .c, .js, .py, .rb
• If this -c switch is omitted, compilation will be skipped and the <executable> will by executed. Make sure the <executable> exists.

-l

• Enable logging, creates run.log for logging monitor infomation
• Includes execution time, memory usage and output size (bytes written to stdout and stderr respectively)

-s

• Silence mode, suppress compiler messages if -c switch is on, and result json which will be printed at the end

IO Setting Options

Options related to I/O.

-I

• Redirect stdin to files named stdin[0-*]
• Default is read stdin stream, and multiple test case input should be a string using \x00 as delimiter:
  • [ in_0 \x00 in_1 \x00 ... in_n-1 \x00 ]
• This switch must be used along with docker run -i

  Note:

  • Inputs containing \x00 is NOT supported in multiple test cases streaming mode!
  • Streaming with large input (>1MB) is NOT RECOMMENED in multiple test cases mode as it may cause performance issues!

-O

• Redirect stdout to files named stdout[0-*]
• Default is write stdout stream, and multiple test case output will be a continuous string:
  • [ out_0 out_1 ... out_n-1 ]
  • use the stdout_size array in the result json to determine length of each stdout

-E

• Redirect stderr to files named stderr[0-*]
• Default is write stderr stream, and multiple test case output will be a continuous string:
  • [ err_0 err_1 ... err_n-1 ]
  • use the stderr_size array in the result json to determine length of each stdout

-C

• Redirect compile messages to file cmsg.txt
• Default is write the stdout at the beginning, will also insert a null character in the beginning of stderr
  • stdout: [ cmsg \x00 out_0 ... ]
  • stderr: [ <empty> \x00 err_0 ... ]
• No file will be created nor data will be written to if -c switch is off or -s switch is on

-R

• Redirect result json to file result.json
• Default is write the stdout at the end with a \x00 delimiter at the beginning
  • stdout: [ ... \x00 result_json ]
• No file will be created nor data will be written to if -s switch is on

Monitor Setting Options

Options controlling the monitor program behavior.

-e <level>

• Error tolerance level
• Stop if a test case encouter an error
  • 0 = Stop on all errors (default)
  • 1 = Stop on Time Limit Exceed and Compile Error
  • 2 = Stop only if Compile Error

-n <num_input>

• Number of test cases input (default = 1)
• 0 means stdin is closed

-t <time_lim_s>

• Time limit in seconds (default = 0 = unlimited)

-m <mem_lim_mb>

• Memory limit in MB (default = 0 = unlimited)

-o <out_lim_kb>

• Output limit in KB, (default = 0 = unlimited)

Result Json Format

The properties of the result json.

{
    "result": [string, ...],
    "stdout_size": [int, ...],
    "stderr_size": [int, ...],
    "execute_time": [double, ...],
    "memory_usage": [int, ...]
}

result

• Result string of corresponding test cases, each would be one of these:
• OK, Compile Error, Executable Not Found, Runtime Error, Time Limit Exceed, Memory Limit Exceed, Output Limit Exceed, System Resource Exceed, Bad System Call, Judge Error

stdout_size

• The stdout size of corresponding test cases, useful when using multiple test case mode with -O switch is off

stderr_size

• The stderr size of corresponding test cases, useful when using multiple test case mode with -E switch is off

execute_time

• The execution time of corresponding test cases, in seconds.

memory_usage

• The peak resident memory usage of corresponding test cases, in bytes.

Parse Streams in Streaming Mode

The output format of stdout and stderr streams when using streaming mode.

By default, three streams will be write to stdout: compile message cmsg, outputs of child out_x, result json json.

The switches -C, -O, -R, and -s control which of them will be write to stdout. When more than one stream that will be written to stdout, then there will be a delimiter \x00 between them.

Below shows the table concerning when there will be a delimiter \x00:

0 = write to stdout stream, 1 = redirected to files

Stdout

Stderr

Navigate Wiki Pages

• Run Reference
• Technology
• Testing
• Use Case
• Development

Back to Home